home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1995 November / EnigmA AMIGA RUN 02 (1995)(G.R. Edizioni)(IT)[!][issue 1995-11][Skylink CD].iso / earcd / program / misc / fpl-v13.lha / fpl / docs / FPLdoc.doc < prev    next >
Text File  |  1995-03-01  |  20KB  |  510 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.                                      FPL
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31.  
  32.                          Generated with Heddley v1.1
  33.                       Heddley v1.1 (C) Edd Dumbill 1994
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.                                   - Page 1 -
  73.  
  74.  
  75.  
  76. 1.    FPL General Documentation
  77.  
  78.  FPL is Copyright © 1992-1994 by  FrexxWare . Permission is granted to freely
  79. distribute this program for non-commercial purposes only. FPL is distributed
  80. "as is"  without warranty  of any kind.
  81.  
  82.  This documents the FPL language as it runs from version 11. If you happen to
  83. use any lower version, upgrade!
  84.  
  85.      Installation            How to install FPL library!
  86.      About the project       Read about the project!
  87.      Bug reports             How to report bugs?
  88.      Distribution rights     Freely destributable?
  89.      Files in package        What are the files in the package?
  90.      Requirements            What hardware is required?
  91.      Warranty                What is guaranteed?
  92.  
  93. Programmers that want to code FPL:
  94.      FPL programming         
  95.  
  96. And for programmers that want to implement FPL library support:
  97.      Library implementation  How to implement FPL!
  98.  
  99. 2.    Installation
  100.  
  101.     AMIGA
  102.     =====
  103.   Copy the file "fpl.library" into your LIBS: directory. If you have a 68020
  104. (or later) processor, copy the file found in the subdirectory "020/" to your
  105. LIBS: instead of the other file.
  106.  
  107.   Make an FPL: assign in your user-startup to the root directory of the FPL
  108. tree.
  109.  
  110.   If you ever intend to do anyting yourself with the fpl.library, you should
  111. consider copying the 'include/' directory tree to INCLUDE:.
  112.  
  113.     OTHER
  114.     =====
  115.   FPL have not been used by me "for real" in other systems than Amiga, which
  116. makes installation procedure and other stuff to remain undocumented. Please
  117. contribute with your experiences!
  118.  
  119. 3.    No warranty
  120.  
  121.   BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE
  122. LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE
  123. STATED IN WRITING THE COPYRIGHT HOLDERS PROVIDE THE LIBRARY "AS IS" WITHOUT
  124. WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED
  125. TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  126. PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE LIBRARY IS
  127. WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
  128. NECESSARY SERVICING, REPAIR OR CORRECTION.
  129.  
  130.   IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL
  131. ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY REDISTRIBUTE THE LIBRARY AS
  132. PERMITTED, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL,
  133. INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE
  134. THE LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED
  135. INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE
  136. LIBRARY TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER
  137. PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
  138.  
  139. 4.    Distribution
  140.  
  141.  
  142.  
  143.                                   - Page 2 -
  144. 4.    Distribution
  145.  
  146.   ########################################################################
  147.   #                                                                      #
  148.   # This program is free software; you may redistribute for non          #
  149.   # commercial purposes only. Commercial programs must have a written    #
  150.   # permission from the author to use FPL. FPL is *NOT* public domain!   #
  151.   # Any provided source code is only for reference and for assurance     #
  152.   # that users should be able to compile FPL on any operating system     #
  153.   # he/she wants to use it in!                                           #
  154.   #                                                                      #
  155.   # You may not change, resource, patch files or in any way reverse      #
  156.   # engineer anything in the FPL package.                                #
  157.   #                                                                      #
  158.   # This program is distributed in the hope that it will be useful,      #
  159.   # but WITHOUT ANY WARRANTY; without even the implied warranty of       #
  160.   # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.                 #
  161.   #                                                                      #
  162.   # Daniel Stenberg                                                      #
  163.   # Ankdammsgatan 36, 4tr                                                #
  164.   # S-171 43 Solna                                                       #
  165.   # Sweden                                                               #
  166.   #                                                                      #
  167.   # FidoNet 2:201/328    email:dast@sth.frontec.se                       #
  168.   #                                                                      #
  169.   ########################################################################
  170.  
  171. 5.    Files in the package
  172.  
  173. Files included in the FPL package:
  174.  
  175. [root] (dir):   Main files of the FPL package.
  176.  
  177.   demo.FPL              FPL program featuring almost everything the language
  178.                         includes. Run this by entering "src/SFPL demo.FPL".
  179.   HISTORY               Changes to FPL during history. Important information
  180.                         if you are updating from an older version.
  181.   FUTURE                Changes that will be done to FPL in the near and far
  182.                         future.
  183.   README                Short text about what FPL is.
  184.  
  185. docs (dir):
  186.  
  187.   FPLdoc.guide          General FPL distribution details. Bug reports,
  188.                         distribution rights and more.
  189.  
  190.   FPLuser.guide         Programming language documentation. Including
  191.                         programming  concepts  and  examples .
  192.  
  193.   FPLlib.guide          Documentation covering fpl.library. How to implement
  194.                         it in your own code and all that has to be done to
  195.                         create a comforable FPL environment.
  196.  
  197.   fpl.doc               autodoc formatted fpl.library function reference
  198. file.
  199.  
  200.   FPL.README            Short text to include in software packages where FPL
  201.                         is used!
  202.  
  203. FPL (dir):      FPL program examples. Check out these programs to learn about
  204.                 FPL programming.
  205.  
  206.   char2ASCII.FPL        Asks for a character and outputs it's ASCII code.
  207.   ASCII2char.FPL        Ascs for an ASCII code and output the character.
  208.  
  209. util (dir):     fpl.library implementation examples. 
  210.  
  211.   FrexxCalc.c           Source code to FrexxCalc. Execute to compile.
  212.                         FrexxCalc - the utility - is an advanced command line
  213.  
  214.                                   - Page 3 -
  215. 5.    Files in the package
  216.  
  217.                         calculator which is especially made for people who
  218.                         wants a calculator able to evaluate the result of
  219.                         C  expressions .
  220.  
  221.   FrexxCalc.doc         Short documentation file to the uper util
  222.  
  223.   LibList               New Amiga library management utility.
  224.  
  225.   LibList.doc           Short documentation file to the uper util
  226.  
  227. src (dir):      FPL source code
  228.  
  229.   COMPILING             Read this to get information about how to compile.
  230.   Makefile              (UNIX) Uncomment the lines affecting the machine
  231.                         you're compiling on!
  232.   smakefile             (Amiga) SAS/C version of the makefile.
  233.   [the rest]            FPL shared library Source code. 
  234.  
  235. --- Amiga only: ---
  236.  
  237.   fpl.library           FPL library! Must be placed in your LIBS: directory.
  238.  
  239. debug (dir):    FPL debugger source directory
  240.  
  241. funclib (dir):  Funclib development directory
  242.  
  243. include (dir):  Include file tree to fpl.library. Copy them all to INCLUDE:
  244.  
  245. 6.    Requirements
  246.  
  247.   FPL is a platform independent script language. There will be different
  248. requirements in different environments.
  249.  
  250. AMIGA:
  251.   fpl.library should work on all Amigas using AmigaDos version 1.2
  252. (dos.library V33) or higher.
  253.  
  254. 7.    Bug reports
  255.  
  256.   Sometimes you will encounter a bug in FPL. Although I cannot promise I can
  257. or will fix the bug (I might not even agree it's a bug!), I want to hear about
  258. any bugs you encounter, just in case I do want to fix them.
  259.  
  260.   To make it possible for me to fix a bug, you have to report it. In order to
  261. do so you must know  how to recognize one  and  how to report it .
  262.  
  263. 8.    What is a bug?
  264.  
  265.   FPL is executed as a part of a software not necessary coded by  FrexxWare .
  266. Errors that occur are _very_ hard for the user to trace back to the library
  267. and you should as a FPL programmer complain to the software programmer who, if
  268. it really turns out to be an FPL problem, reports it to me.
  269.  
  270.   If FPL executes an illegal instruction, or dies with an operating system
  271. error message that indicates a problem in the program (as opposed to something
  272. like "disk full"), it's most certainly a bug.
  273.  
  274.   Taking forever to complete a command can be a bug, but you must make certain
  275. that it really was FPL's fault. Some commands simply take a long time. If the
  276. input was such that you KNOW it should have been processed quickly, report it
  277. as a bug. If you don't know whether the command should take a long time, find
  278. out by looking in the manual or by asking for assistance.
  279.  
  280.   If a command you are familiar with causes an FPL error message in a case
  281. where its usual definition ought to be reasonable, it is probably a bug.
  282.  
  283.   If a command does the wrong thing, that is a bug. But be sure you know for
  284.  
  285.                                   - Page 4 -
  286. 8.    What is a bug?
  287.  
  288. certain what it ought to have done. If you aren't familiar with the command,
  289. or don't know for certain how the command is supposed to work, then it might
  290. actually be working right. Rather than jumping to conclusions, show the
  291. problem to someone who knows for certain.
  292.  
  293.   Finally, a command's intended definition may not be best for coding with.
  294. This is a very important sort of problem, but it is also a matter of judgment.
  295. Also, it is easy to come to such a conclusion out of ignorance of some of the
  296. existing features. It is probably best not to complain about such a problem
  297. until you have checked the documentation in the usual ways, feel confident
  298. that you understand it, and know for certain that what you want is not
  299. available. If you are not sure what the command is supposed to do after a
  300. careful reading of the manual, check the index and glossary for any terms that
  301. may be unclear. If you still do not understand, this indicates a bug in the
  302. manual. The manual's job is to make everything clear. It is just as important
  303. to report documentation bugs as to report program bugs.
  304.  
  305.   Since the AmigaDos and some other OSes lacks the beauty called memory
  306. protection, the memory allocated by FPL might get changed by another process
  307. than FPL itself. Therefore you must be sure of that there is none of the other
  308. programs running together with FPL that might be the cause of the bug.
  309.  
  310.   FPL puts a lot of responsibility on the coder using the library. Returning
  311. wrong values, freeing wrong variables, missing assigns etc, etc may just be
  312. the crashing/failing/bugging reason. Before complaining to me, first complain
  313. to the coder of the software you're controlling with FPL, and make absolutely
  314. sure he has followed the coding guidelines.
  315.  
  316.   The very useful Amiga debugging tools Mungwall and Enforcer are excellent
  317. tools to track illegal memory accesses and other violations. Do use the
  318. versions that can work together with the `SegTracker' to be able to more
  319. clearly distiguish whether it's fpl.library that bugs or the host software.
  320.  
  321. 9.    How to report a bug
  322.  
  323.   When you decide that there is a bug, it is important to report it and to
  324. report it in a useful way. A useful bug report is an exact description or why
  325. not a copy of the FPL program executed and a detailed description of the
  326. effects of the suspected bug.
  327.  
  328.   The most important principle in reporting a bug is to report FACTS, not
  329. hypotheses or categorizations. It is always easier to report the facts, but
  330. people seem to prefer to strain to posit explanations and report them instead.
  331. If the explanations are based on guesses about how FPL is implemented, they
  332. will be useless; I will have to try to figure out what the facts must have
  333. been to lead to such speculations. Sometimes this is impossible. In any case,
  334. that is unnecessary and time-consuming work for us.
  335.  
  336.   Amigas and AmigaDos exist in extremely many different configurations. When
  337. reporting a suspicious behavior, include information such as Amiga model, OS
  338. version, amount of memory (both chip and fast) and all other useful data such
  339. as processor, MMU and co-processors (I advise you to simply include the output
  340. made with Sysinfo). Also make sure you always include the version number of
  341. the library you are using (on Amiga: the cli command "version FULL
  342. fpl.library" will give answer to the uncertain) and which program you used FPL
  343. in when you discovered the bug.
  344.  
  345.   Report the bug through our BBS, paper mail, email or voice phone. See
  346.  how to reach us  for information on how.
  347.  
  348.   Once again, I do not promise to fix the bug; if the bug is serious, or ugly,
  349. or easy to fix, I probably will.
  350.  
  351. 10.    About the project
  352.  
  353.      What is FPL?  
  354.      Who made FPL? 
  355.  
  356.                                   - Page 5 -
  357. 10.    About the project
  358.  
  359.      Why make FPL? 
  360.      Why use FPL?  
  361.  
  362.   FPL has been developed almost entirely under UNIX using memory protection.
  363.  
  364.   The Amiga version is edited, tested and run error free with Mungwall and
  365. Enforcer as background processes.
  366.  
  367.   SAS/C Development System's symbolic debugger `cpr' is *NOT* fun to use when
  368. debugging FPL. The amount of linked lists is large and `cpr' handles them
  369. badly. (In my opinion, the debugger is the weakest part of that, in all other
  370. ways superb, package.) Although the ability to debug shared libraries is
  371. extremely valuable!
  372.  
  373.   FPL is currently being used in the major  FrexxWare  project called FrexxEd.
  374. A highly customizable, programmable, zero limitation text editor (running only
  375. at Amiga beta testers at the moment). If you decide to use FPL in your
  376. application, please let me know!
  377.  
  378.   I started coding on this project in the beginning of the summer 1992 and
  379. since the 2nd of November 1992, it has been released, used and improved.
  380.  
  381.   Any suggestions regarding FPL or the library implementation part, is warmly
  382. welcomed. I aim on making FPL superb!
  383.  
  384. 11.    What is FPL?
  385.  
  386.   FPL (pronounced 'eff-pee-ell') is an advanced flexible real-time ASCII text
  387. interpreting multi-file shared library programming language very much inspired
  388. by the C programming language.
  389.  
  390.   We say that FPL is "advanced" because there are several ways to solve each
  391. programming task, because there are many keywords, functions and expression
  392. operators and they enable advanced coding.
  393.  
  394.   We call FPL "flexible" since there is much left to the coder of the software
  395. FPL is used in, to create functions and variables that will exist in the FPL
  396. programs for that software.
  397.  
  398.   "real-time" means that FPL does all interpreting and execution at invoke
  399. time, with nothing compiled, tokenized or preprocessed. (Even though such
  400. possibilities will be implemented in the future versions.)
  401.  
  402.   "ASCII text" means that FPL executes simple texts created in any text editor
  403. (I recommend FrexxEd, which is Freeware, highly programmable through FPL and
  404. Copyright © by  FrexxWare . Yet only available for amiga beta testers...).
  405.  
  406.   "Interpreting" means that the instructions are read one by one and are
  407. executed as soon as possible.
  408.  
  409.   "multi-file" means that functions and variables can be accessed and
  410. controlled in any number of files at the same time. Using one or several files
  411. are the same to FPL internals.
  412.  
  413.   "shared library" means that the entire language is constructed as a
  414. selfgovering part of the programs that are using it. When several programs are
  415. using FPL at the same time, only one code is loaded into memory. Upgrading the
  416. language is not harder than copying new versions of the language to your LIBS:
  417. direcrory! (on Amiga).
  418.  
  419.   The fact that FPL is inspired by C is very much noticeable. The code looks
  420. and feels almost exactly as C code does.
  421.  
  422.   FPL is extremely powerful and practical when you want your software to
  423. include an interpreting language with possibilities for the user himself to
  424. create his own functions, text formatters, word interpreters, advanced macros,
  425. entire programs, etc, etc... The only restriction is the limit of your mind.
  426.  
  427.                                   - Page 6 -
  428. 11.    What is FPL?
  429.  
  430.  
  431.   FPL is Freeware, not public domain. Coded for free, given away for free, to
  432. be used for free.
  433.  
  434. (The word 'Frexx' comes from an internal joke among our friends as a word for
  435. cool/good/groovy/nice or something like that!)
  436.  
  437. 12.    Who made FPL?
  438.  
  439.   FPL is programmed mainly by me, Daniel Stenberg, but I got plenty additional
  440. help and ideas from Kjell Ericson (who coded the stack allocating and
  441. expanding routines), Linus Nielsen (who helped me develop my thoughts around
  442. the memory allocation/dealloction re-cycling/caching scheme and compiled it
  443. under HPUX) and Björn Stenberg (who gave me ideas and made the first ports to
  444. SunOS and Dell Unix!).
  445.  
  446.   We produce our software together under the FrexxWare label.
  447.  
  448.   FrexxWare has released a bunch of small and hopefully useful freely
  449. distributed utilities, mainly for use in a development environment such as our
  450. own! Get in touch for  more information !
  451.  
  452.   Lots of ideas also come from Jonas Engstrom (who's language nowadays seems
  453. very poor compared to FPL... :-), Tord Persson (who really have inspired me to
  454. continue towards a full C interpreter), Niclas Emdelius (who due to his
  455. troubles implementing FPL in his program has thought of some great ideas to
  456. make reality), Stefan Boberg and Lasse Mickos (who in combination with Björn
  457. finally made me insert single function invoke support).
  458.  
  459.   I've spent several hundreds of hours on this and yet I've done most of the
  460. coding under UNIX (or more correctly AIX on a beautiful RS/6000) enjoying real
  461. compiling speed instead of my slow machine at home... (Which until the end of
  462. September 1992 was a A500 but since then is a A3000.)
  463.  
  464. 13.    Why make FPL?
  465.  
  466.   We needed an interpreting script language for our text editor, and I made it
  467. entirely for that purpose. Later on we figured out about a dozen of other
  468. products that really could have use for a language like this (not the least a
  469. few interesting projects we have been thinking of), and we noticed that
  470. creating a library of the code wouldn't be that hard.
  471.  
  472.   Software developers in need for a script language will no longer have to
  473. code their own. FPL is the solution. FPL is for everyone!
  474.  
  475. 14.    Why use FPL?
  476.  
  477.  FPL has everything a programming language should have.
  478.  
  479.  FPL programs are possible to write very short and compact.
  480.  
  481.  FPL interprets common ASCII-files, needing no compiling at all. (Although
  482. compiling will become a future feature!)
  483.  
  484.  FPL is very similar to C. If you know C, you know FPL.
  485.  
  486.  FPL is very easy to include in your own code and an excellent tool to
  487. batch/macro control your software.
  488.  
  489.  FPL is a language on shared library which makes updating the language
  490. extremely fast, easy and flexible. (At the moment Amiga, OS/2 and SVR4 UNIX
  491. only)
  492.  
  493.  FPL is free.
  494.  
  495.  FPL is a fully resource tracking system. All memory used by FPL is removed
  496. whenever any FPL program exits.
  497.  
  498.                                   - Page 7 -
  499. 14.    Why use FPL?
  500.  
  501.  
  502.  FPL is a platform independent language available in several operating
  503. systems. And if it isn't already available, porting it to yet another is very
  504. simple! When porting your application(s) to other OS'es, the FPL programs will
  505. work *exactly* the same!!!
  506.  
  507.  FPL source code is available. You are guaranteed to always have nothing less
  508. than the latest FPL version to start from in case of the software support is
  509. dropped.
  510.